home *** CD-ROM | disk | FTP | other *** search
/ JCSM Shareware Collection 1993 November / JCSM Shareware Collection - 1993-11.iso / cl720 / codelist.lzh / MANUAL.DOC < prev    next >
Text File  |  1993-08-17  |  21KB  |  842 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                           CODELISTER
  16.  
  17.  
  18.  
  19.                                      
  20.                                   USER'S       MANUAL
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35. MALCOLM MCDOWELL
  36. 85 Halley St.,
  37. Nepean Ontario
  38. K2J 3R5
  39. Canada
  40.  
  41. (613) 825-8593
  42.  
  43.  
  44. .
  45.  
  46.  
  47.  
  48. WARRANTY
  49.  
  50. Users of "CodeLister" must accept this disclaimer of warranty:
  51.  
  52. "CodeLister" is supplied as is.  The author disclaims all warranties, expressed or implied, including, without
  53. limitation, the warranties of merchantability and of fitness for any purpose.  The author assumes no liability for
  54. damages, direct or consequential, which may result from the use of "CodeLister."
  55.  
  56.  
  57. USE RESTRICTIONS
  58.  
  59. Malcolm McDowell gives you a non-exclusive license to use the registered version of CodeLister.  The
  60. program and documentation are copyright by Malcolm McDowell. You may not make copies of this registered
  61. version of "CodeLister" without authorization from Malcolm McDowell.   A single user license  is granted for
  62. "CodeLister" for use on only one computer at any time.  Site license copies may be used over a network as
  63. long as the number of users does not exceed  the number of users for the site license.  You may not make
  64. copies nor distribute the program or documentation to a third party.
  65.  
  66.  
  67.  
  68.  
  69.  
  70.     OMBUDSMAN NOTICE
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81. This program is produced by a member of the Association of Software Professionals (ASP). ASP wants to make
  82. sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with
  83. an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help
  84. you resolve a dispute or problem with an ASP member, but does not provide technical support for members'
  85. products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send a
  86. CompuServe message via CompuServe Main to ASP Ombudsman 70007,3536.
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111. CONTENTS
  112.  
  113.  
  114. CHAPTER 1  -  INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . .  1
  115.      1.1 System Requirements.. . . . . . . . . . . . . . . . . . . . . .  1
  116.      1.2 Features. . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
  117.  
  118. CHAPTER 2  INSTALLATION. . . . . . . . . . . . . . . . . . . . . . . . .  2
  119.  
  120. CHAPTER 3  PROJECT FILES . . . . . . . . . . . . . . . . . . . . . . . .  3
  121.      3.1 Project File Extension. . . . . . . . . . . . . . . . . . . . .  3
  122.      3.2 Creating Project Files. . . . . . . . . . . . . . . . . . . . .  3
  123.  
  124. CHAPTER 4  RUNNING CODELISTER. . . . . . . . . . . . . . . . . . . . . .  4
  125.      4.1 Printing Individual Files.. . . . . . . . . . . . . . . . . . .  4
  126.      4.2 Printing Project Files. . . . . . . . . . . . . . . . . . . . .  4
  127.      4.3  Definition of CodeLister Display.. . . . . . . . . . . . . . .  5
  128.           4.3.1  Printing Files. . . . . . . . . . . . . . . . . . . . .  6
  129.                4.3.1.1 Stopping the Printing of Files. . . . . . . . . .  6
  130.  
  131. CHAPTER  5  SETTING THE CONFIGURATION. . . . . . . . . . . . . . . . . .  7
  132.      5.1 Selecting Configuration Parameters. . . . . . . . . . . . . . .  7
  133.  
  134. CHAPTER 6 DEFINITION OF LISTINGS . . . . . . . . . . . . . . . . . . . . 11
  135.  
  136. CHAPTER 7  ERROR MESSAGES. . . . . . . . . . . . . . . . . . . . . . . . 12
  137.  
  138. CHAPTER 8  - SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . 13
  139.  
  140.  
  141.  
  142.  
  143.  
  144. CHAPTER 1  -  INTRODUCTION
  145.  
  146.  
  147.  
  148. 1.1 System Requirements.
  149.  
  150.      CodeLister is designed to run on DOS 4.00 or higher. A VGA monitor is recommended. The printers
  151.      supported include, standard graphics printers such as:
  152.  
  153.                EPSON
  154.                ROLAND
  155.  
  156.      and laser printers such as:
  157.  
  158.                HP LASERJET II
  159.                HP LASERJET III.
  160.  
  161. 1.2 Features.
  162.  
  163.      CodeLister is a package used to support source code development and configuration management. Its
  164.      features include:
  165.  
  166.      ■    Formatted C source code printouts.
  167.  
  168.                CodeLister will take individual source files or project files and format them for
  169.                printing. This prevents lines of text being printed on the perforations or off the page.
  170.  
  171.      ■    Each page is identified with a header.
  172.  
  173.                The header contains the file name, the date that the file was edited and saved and the
  174.                page number. This allows you to identify printouts belonging to a given date and
  175.                configuration.
  176.  
  177.      ■    Multiple Pages on a single sheet of paper.
  178.  
  179.                If you are using a laser printer, CodeLister can generate listings that have one, two or
  180.                four pages on each sheet of paper. This is ideal for storing old listings and saving
  181.                paper.
  182.  
  183.      ■    Table of Contents.
  184.  
  185.                A Table of Contents lists the functions and the page in the listing where each is
  186.                defined. This allows you to quickly locate a function in the listing.
  187.  
  188.      ■    Statistics
  189.  
  190.                The number of lines of code and the size, in bytes, of the ASCII files.
  191. CHAPTER 2  INSTALLATION
  192.  
  193.  
  194.  
  195.  
  196. To install  CodeLister, perform the following steps:
  197.  
  198. 1)   Insert the diskette labelled CODELISTER  V1.21 into either disk drive A or B.
  199.  
  200. 2)   If you inserted the diskette in drive a:, then at the DOS prompt type:
  201.  
  202.      >a:
  203.  
  204.        or
  205.  
  206.      If you inserted the diskette in drive b:, then at the DOS prompt type:
  207.  
  208.      >b:
  209.  
  210. 3)   Then type:
  211.  
  212.      > INSTALL
  213.  
  214. 4)   The installation will create a directory called C:\CLIST and copy the files:
  215.  
  216.           CLIST.EXE and
  217.           CLIST.CFG
  218.  
  219.      to that directory.
  220.  
  221.  
  222. 5)   Add the directory to your path name. Use your editor to add the path to autoexec.bat file. This is done
  223.      by adding:
  224.  
  225.           ;c:\clist
  226.  
  227.      to the line that has "PATH=" in your autoexec.bat file.
  228.  
  229. Your are now ready to execute CodeLister from any directory on your computer.
  230.  
  231.  
  232.  
  233.      NOTE:          CodeLister will create a configuration file in each directory
  234.                     that you execute it from.
  235.  
  236. CHAPTER 3  PROJECT FILES
  237.  
  238.  
  239.  
  240.  
  241. CodeLister accepts project files as input. A PROJECT FILE is defined as a file containing a list of source code
  242. files that are to be formatted and printed.
  243.  
  244. When a project file is used to print your source code, page number 1 starts with the first file and page numbers
  245. will continue sequentially until the last source file is printed. The Table of Contents includes all functions in the
  246. project file.  Statistics printed will include the total number of lines and size, in bytes, for all files defined in the
  247. project file.
  248.  
  249. 3.1 Project File Extension.
  250.  
  251.      CodeLister will assume that the project file has a .PRJ extension, but any extension can be used
  252.      provided that it is entered on the command line with the extension such as:
  253.  
  254.                clist -p project.fil
  255.  
  256. 3.2 Creating Project Files.
  257.  
  258.      To create a project file edit a file that contains all of your C source code.  Example project files are
  259.      shown:
  260.  
  261.                main.c
  262.                function1.c
  263.                function2.c
  264.                function3.c
  265.                function1.h
  266.                function2.h
  267.  
  268.                     or
  269.  
  270.                main
  271.                function1
  272.                function2
  273.                function3
  274.                function1.h
  275.                function2.h
  276.  
  277. Note that some file names exclude the ".c" extension.  If the file to be printed, is a ".h" file, make sure the
  278. ".h" extension is included in the file name.  This is especially important when a file name has both  a ".c"
  279. and ".h" extension. For example:
  280.  
  281.           function1.c     and     function2.h
  282.  
  283.      All files without the extension are assumed to be a .c file.
  284. CHAPTER 4  RUNNING CODELISTER
  285.  
  286.  
  287.  
  288. The section describes how to run CodeLister.  You may print either individual source files, or project files.  To
  289. run CodeLister one of two command line parameters must be specified. One command line parameter is to tell
  290. CodeLister that the file to print is a single "c" source file and the other is to print a project file, which contains
  291. a list of "c" files.
  292.  
  293. 4.1 Printing Individual Files.
  294.  
  295.      A single source file is printed by typing the following at the DOS prompt:
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308. 4.2 Printing Project Files.
  309.  
  310.      To distinguish between a source file and a project file, the -p command line entry is typed before the
  311.      project file name is entered.   The project file extension is assumed to be .prj, if no extension is
  312.      provided.
  313.  
  314.                Make sure that you leave a space between the -p and the project
  315.                file name.
  316.  
  317.      A project file is printed by typing the following at the DOS prompt:
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338. 4.3  Definition of CodeLister Display.
  339.  
  340.      If CodeLister has a valid configuration file, the  parameters are displayed, informing you of the type of
  341.      printout that will be performed. If a configuration file is not found, then CodeLister will automatically
  342.      prompt you for the information as defined in chapter 5.  Otherwise, CodeLister shows the information
  343.      in the following display:
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.      The prompt:
  369.                 CodeLister will print source file:  test 
  370.  
  371.      indicates the file that you requested to be printed. When CodeLister detects a project file the prompt
  372.      will be:
  373.  
  374.                CodeLister will print project file:  project
  375.  
  376.      Function keys, shown in the display, have the following purpose:
  377.  
  378.      F1 - Select Configuration.
  379.  
  380.           To modify the configuration, select F1. Refer to chapter 5 for a description of the
  381.           prompts.
  382.  
  383.      F2  - Print.
  384.  
  385.           If you select F2, CodeLister prints the source files.
  386.  
  387.  
  388.      F10 - Exit.    
  389.  
  390.           Function key F10 allows you to exit from CodeLister without printing.
  391.  
  392. 4.3.1  Printing Files.
  393.  
  394.      When F2 - Print is selected, CodeLister  informs you of the file that is being printed, by displaying the
  395.      message:
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.      Printing file "name" is the name of the source file which is being printed.
  421.  
  422. 4.3.1.1 Stopping the Printing of Files.
  423.  
  424.      If during the printing phase  you must stop printing, press Esc. The message:
  425.  
  426.           Press 'Esc' to stop printing
  427.  
  428.      is displayed. To stop printing, press Esc a second time and you will exit CodeLister. If you want to
  429.      resume printing press any key.
  430.  
  431.  
  432. CHAPTER  5  SETTING THE CONFIGURATION
  433.  
  434.  
  435.  
  436. This  chapter describes the initialization of CodeLister configuration parameters. If CodeLister does not have a
  437. valid configuration file, or you wish to change the configuration, by selecting F1 - Set Configuration  from the
  438. main menu, the series of prompts, identified in this chapter are displayed.
  439.  
  440. Valid parameters are listed in each prompt between the brackets, [ and ]. Using the example prompt,
  441.  
  442.      Enter value [ 1 or 2 ] ?
  443.  
  444. the valid parameters are [ 1 or 2 ], so you can enter either 1 or 2. If an error is made you will hear a beep and
  445. the error message Invalid Entry will be displayed, momentarily, on the lower line of the screen. If this occurs
  446. edit the parameter to match one of those in the brackets.
  447.  
  448. The default parameters are displayed after the question mark (?). In the example prompt: 
  449.  
  450.      Enter value [ 1 or 2 ] ? 1
  451.  
  452. The value  1 following the ? is the default parameter. The default parameters are obtained from your
  453. configuration file. To change a parameter, you can use the DEL or Backspace key and type the appropriate
  454. entry. To accept the default parameter, simply press ENTER.
  455.  
  456. 5.1 Selecting Configuration Parameters.
  457.  
  458. This section describes the series of prompts used to choose the configuration. The selections include the printer
  459. type, the printer port and the format of the output. These  parameters allow CodeLister to communicate with the
  460. appropriate printer and provide the output suitable to your needs.
  461.  
  462.  
  463.  
  464. Selecting Printer Type....
  465.  
  466.  
  467.      The first prompt is:
  468.  
  469.      
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.      Standard graphics printers  include:
  483.  
  484.                1) EPSON and ROLAND  or
  485.  
  486.      Laser printers include:
  487.  
  488.                2) HP LaserJet II and III and compatibles.
  489.  
  490.      If you are using a standard graphics printer, enter 1. If you are using a
  491.      Laser printer enter 2 or 3. The default is 1 or Standard Graphics Printer.
  492.  
  493.  
  494.  
  495. Select Character Style...
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.      If Compressed style is selected, more characters are printed in a line.
  514.  
  515.  
  516.  
  517. Select Page Format...
  518.  
  519.  
  520.      The select page format prompt is only displayed if you selected output to a laser printer. The standard
  521.      graphics printer selection defaults to single page format.
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.      Selection 1, will print a single page on an a full 8 ½ by 11  sheet of paper  If you select 2, then two
  540.      pages will be printed on a single sheet. If you select 3, then four pages will be printed on a sheet of
  541.      paper.  Enter your selection.  
  542.  
  543.  
  544.  
  545.  
  546. Select Printer Port...
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.      The printer port is the port that the printer is attached to. The possible selections include  lpt1, lpt2 or
  566.      lpt3.  Enter the appropriate selection. For a standard DOS configuration your printer is located on lpt1.
  567.      
  568.  
  569.  
  570.  
  571.  
  572.  
  573. Select Border...
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.      If you wish to have a border around the page enter y.  If you select n, the header has a line printed to
  589.      separate it from the source listing and a line at the bottom of the page.
  590.  
  591.      
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601. Select Table of Contents...
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.      If you wish to have a table of contents printed at the end of the listing enter y.  If you select n, no
  614.      table of contents is printer.   If you select Y, then the follwoing prompt will appear:
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.      If you wish your Table of Contents to be sort by page, enter 1. If you wish to have the Table of
  631.      Contents sorted by function name, enter 2. 
  632.  
  633.      An example of a sort by page is:
  634.  
  635.      main()....................................................... 1
  636.      DoThis() ..................................................2
  637.      ItIsTime() ...............................................2
  638.      DoneNow() ..........................................4
  639.  
  640.      The same page sorted by function would appear as:
  641.  
  642.      DoneNow() ..........................................4
  643.      DoThis() ..................................................2
  644.      ItIsTime() ...............................................2
  645.      main()....................................................... 1
  646.  
  647.  
  648.  
  649. Select Statistics....
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.      If you wish to have statistics printed enter y.  If you select n, no statistics are printed.
  663.  
  664.  
  665. When the parameters have been initialized, the display, Current Configuration is displayed.
  666.  
  667. CHAPTER 6 DEFINITION OF LISTINGS
  668.  
  669.  
  670.  
  671.  
  672. Each page of the listing contains the following sections:
  673.  
  674. o Header containing:
  675.  
  676.      LISTING OF: This is the name of the file whose source code is printed on the page.
  677.  
  678.      EDIT DATE: This is the date that the source file was last edited and the source code was saved.
  679.  
  680.      Page the number of the page being printed.
  681.  
  682. o Source Code Area
  683.  
  684.      This section contains the source code which is printed with or without a boarder.
  685.  
  686. When all of the source code has been printed, the Table of Contents and the Statistics are printed, if they were
  687. requested during the initialization of the configuration parameters.
  688.  
  689. An example of the Table of Contents is shown:
  690.  
  691.  
  692. TABLE OF CONTENTS
  693.  
  694.      Function(int a, int b, char *string)  ..................... 1
  695.      This( void) ...................................................... 2
  696.      That (long time) ............................................... 3
  697.  
  698.  
  699. On the left side is the name of the function and its parameters. On the right side is the page number that the
  700. function is defined on.
  701.  
  702. An example of the Statistics display is shown:
  703.  
  704.      Total Size of files (bytes)    3000
  705.      Total number of lines          100
  706.  
  707. The total number of lines indicates the number of non-blank lines found in the source code file. The total size of
  708. files, is the number of bytes in the files. 
  709.  
  710. CHAPTER 7  ERROR MESSAGES
  711.  
  712.  
  713.  
  714.  
  715. The following is a list of the error messages that appear if CodeLister is unable to perform an action:
  716.  
  717. 1) CL ERROR: Invalid number of parameters.
  718.  
  719.      You entered an invalid number of command line parameters when CL was executed. Example
  720.      command line parameters are: 
  721.  
  722.           clist file.c          or      clist file
  723.  
  724.           clist -p project.prj  or      clist -p project
  725.  
  726. 2) CL ERROR: Cannot open source file 'xxxx.x'
  727.  
  728.      You enter a source file that could not be located. Ensure that the file name is spelled correctly and that
  729.      it exists on the specified directory.
  730.  
  731. 3) CL ERROR: Cannot open project file 'xxxx.prj'
  732.  
  733.      You enter a project file, that could not be located. Ensure that the project file name is spelled correctly
  734.      and that it exists on the specified directory.
  735.  
  736. 4) CL ERROR: Unable to create configuration file.
  737.  
  738.      CodeLister was unable to create the configuration that is used to store the default parameter for the
  739.      printer type, printer port. This is probably because the directory that the file is to be written to is full.
  740.  
  741.      CodeLister continues with the printing of files, however the parameters must be re-entered the next
  742.      time is run.
  743.  
  744. 5) CL ERROR: Printer not responding.
  745.  
  746.      CodeLister cannot communicate with your printer. Ensure that the printer is either turned on, it is on-
  747.      line or the correct printer port has been selected in configuration parameters.
  748.  
  749.  
  750. CHAPTER 8  - SUPPORT
  751.  
  752.  
  753.  
  754.  
  755. Thank you for registering CodeLister. Your registration entitles you to software support
  756. for 5 months. You will  also be notified of upgrades to CodeLister. 
  757.  
  758.  
  759. Support is available weekdays 4-8pm (eastern time). A telephone answering machine is available. If a message
  760. is left, an attempt will be made to answer by telephone.  I can also be reached by CompuServe. My ID is
  761. 71232,455. If unsuccessful, the response will be by mail.
  762.  
  763.  
  764. I can be reached my mail :
  765.  
  766.                Malcolm D. McDowell
  767.                85 Halley St
  768.                Nepean Ontario
  769.                K2J 3R5
  770.                Canada
  771.  
  772.  
  773.  
  774. If you wish to order additional copies of CodeLister, please forward the following information:
  775.  
  776. ----  Registration Form for NON CREDIT CARD ORDERS --- 
  777.  
  778.  
  779. Name: __________________________________________________________
  780.  
  781. Company: _______________________________________________________
  782.  
  783. Address: _______________________________________________________
  784.  
  785.         ______________________________________________________
  786.  
  787. State/Province _______________    ZIP/Postal Code: _____________
  788.  
  789.  
  790.  
  791. Phone: (_____) _______________   Fax: (_____) __________________
  792.  
  793.  
  794.  
  795.  
  796.  
  797. Type of Diskette for upgrades  5 1/4 ________  or   3 1/2 ______
  798.  
  799. Number of copies to register:
  800.  
  801.        ________ @ 20.00 per copy                      ==>  ________.____
  802.  
  803.        Shipping and Handling                    ==>               2.00
  804.  
  805.                                                          -------------------
  806.  
  807.                          Total                          ==>   ____________
  808.  
  809. Printer(s) Used:
  810.  
  811. ________________________________________________________________
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821. ---   CREDIT CARD ORDERS ONLY ---
  822.  
  823. You can order with MC, Visa, Amex, or Discover from Public (software) Library by calling 800-2424-PsL or
  824. 713-524-6394 or by FAX to 713-524-6398 or by CIS Email to 71355,470. You can also mail credit card orders
  825. to PsL at P.O. Box 35705, Houston, Tx 77235-5705.
  826.  
  827. PLEASE REFER TO PRODUCT NUMBER 10771 WHEN ORDERING.
  828.  
  829. THE ABOVE NUMBERS ARE FOR ORDERS ONLY.  
  830.  
  831. Any questions about the status of the shipment of the order, refunds, registration options, product details,
  832. technical support, volume discounts, dealer pricing, site licenses,etc, must be directed to:
  833.  
  834.           Malcolm D. McDowell
  835.           85 Halley St.,
  836.           Nepean Ontario
  837.           K2J 3R5
  838.           Canada
  839.  
  840.           (613) 825-8593  (4-8 pm weekdays)
  841.  
  842.